rw2: rc.5 version - #3080

Signed-off-by: bwplotka <bwplotka@gmail.com>

* rm2: Async spec support

See
https://docs.google.com/document/d/1AzEt6kOz4MJ855fBxtzvyyS-kDu8ynXiJy6VCSUQcSI/edit

Signed-off-by: bwplotka <bwplotka@gmail.com>

* Update docs/specs/prw/remote_write_spec_2_0.md

Signed-off-by: Bartlomiej Plotka <bwplotka@gmail.com>

* Update docs/specs/prw/remote_write_spec_2_0.md

Co-authored-by: George Krajcsovits <krajorama@users.noreply.github.com>
Signed-off-by: Bartlomiej Plotka <bwplotka@gmail.com>

---------

Signed-off-by: bwplotka <bwplotka@gmail.com>
Signed-off-by: Bartlomiej Plotka <bwplotka@gmail.com>
Co-authored-by: George Krajcsovits <krajorama@users.noreply.github.com>

* RW 2.0-rc.5: allow exemplar-only time series

Prometheus stores exemplars per series, not per sample. populateV2TimeSeries
writes one output TimeSeries per queue item, and for an exemplar item it
appends only an exemplar, so an exemplar can leave the sender in a TimeSeries
of its own. The specification requires every TimeSeries to carry a sample or a
histogram, so that shape is not covered.

Describe it instead of forbidding it, and keep the expectation that the
exemplars travel in the same request as the series they belong to.

Related to prometheus/prometheus#17857 and prometheus/prometheus#16944.

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

* RW 2.0-rc.5: match the embedded protobuf comments

The copy of io.prometheus.write.v2 in this document still says a TimeSeries
specifies samples or histograms, and that exemplars belong to the series'
samples. Neither holds once a TimeSeries can carry exemplars on its own.

krajorama spotted this in review. The same three comments live in
prompb/io/prometheus/write/v2/types.proto, which is the source of truth, so
they are changed there too.

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

* RW 2.0-rc.5: drop the same-request SHOULD

What this PR is about is that an exemplar-only TimeSeries is valid and that it
identifies its series by labels_refs. Whether a sender keeps a series'
exemplars in the same request as its samples is a different question. It is
about interoperability rather than about what the wire format allows, and it
is the part of this change that is under discussion in review.

Taking it out leaves the wire format statement on its own. Co-location is
worth writing down, just not in this rule.

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

* RW 2.0-rc.5: rule out metadata-only time series

The at-least-one rule names samples, histograms and exemplars, so a TimeSeries
carrying only metadata is already invalid. That is left to be inferred from a
list rather than stated, which bwplotka flagged in review.

State it in the rule. Then say what metadata means on the shape this PR adds,
because an exemplar-only TimeSeries still carries the field and the Prometheus
sender fills it. Calling it series-level and letting Receivers ignore it means
a sender cannot rely on that shape to deliver metadata.

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

* RW 2.0-rc.5: apply the review wording

bwplotka's suggestions, applied as given. The at-least-one rule splits into two
bullets and makes the metadata point an example rather than a second clause.
The exemplar bullet loses the sentence about metadata on a sample-less
TimeSeries. The two exemplar comments in the embedded protobuf now say the
exemplars may belong to the series or to its samples and histograms.

Those two comments are the ones prometheus/prometheus#19530 changes in the
source proto, so they move together there, which is what krajorama asked for
when this pair was opened.

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>

---------

Signed-off-by: thc1006 <84045975+thc1006@users.noreply.github.com>